Crate capsule[−][src]
A framework for network function development. Written in Rust, inspired by NetBricks and built on Intel’s Data Plane Development Kit.
The goal of Capsule is to offer an ergonomic framework for network function development that traditionally has high barriers of entry for developers. We’ve created a tool to efficiently manipulate network packets while being type-safe, memory-safe, and thread-safe. Building on DPDK and Rust, Capsule offers:
- a fast packet processor that uses minimum number of CPU cycles.
- a rich packet type system that guarantees memory-safety and thread-safety.
- a declarative programming model that emphasizes simplicity.
- an extensible and testable framework that is easy to develop and maintain.
Getting started
The easiest way to start developing Capsule applications is to use the
Vagrant
virtual machine and the Docker
sandbox provided by the
Capsule team. The sandbox is preconfigured with all the necessary tools and
libraries for Capsule development, including:
- DPDK 19.11
- Clang and LLVM
- Rust 1.50
- rr 5.3
For more information on getting started, please check out Capsule’s README, as well as our sandbox repo for developer environments.
Adding Capsule as a Cargo dependency
[dependencies]
capsule = "0.1"
Using features
To enable test/bench features for example, you can include Capsule in your
Cargo dependencies with the testils
feature flag:
[dev-dependencies]
capsule = { version = "0.1", features = ["testils"] }
Or, to enable the capturing of port traffic to pcap
files
automatically per-port, per-core, you can run a Capsule application with the
pcap-dump
feature flag turned on:
cargo run --features capsule/pcap-dump -- -f capsule-app.toml
Feature flags
default
: Enables metrics by default.metrics
: Enables automaticmetrics
collection.pcap-dump
: Enables capturing port traffic topcap
files.testils
: Enables utilities for unit testing and benchmarking.full
: Enables all features.
Examples
Modules
batch | Combinators that can be applied to batches of packets within a pipeline. |
config | Toml-based configuration for use with Capsule applications. |
metrics | default and metrics Exposes framework metrics, including port, kni, mempool, and pipeline metrics. |
net | Common network utilities. |
packets | Packet types for reading and writing various network protocols. |
testils | testils Utilities for unit tests and benchmarks. |
Macros
compose | Composes the batch builders for the |
ensure | Exits a function early with an |
fieldmap | Defines a mapping of fields to their default values. |
Structs
KniRx | The KNI receive handle. Because the underlying interface is single threaded, we must ensure that only one rx handle is created for each interface. |
KniTxQueue | In memory queue for the cores to deliver packets that are destined for the kernel. Then another pipeline will collect these and forward them on in a thread safe way. |
Mbuf | A DPDK message buffer that carries the network packet. |
PortQueue | The receive and transmit queue abstraction. Instead of modeling them as two standalone queues, in the run-to-completion mode, they are modeled as a queue pair associated with the core that runs the pipeline from receive to send. |
Runtime | The Capsule runtime. |
Enums
UnixSignal | Supported Unix signals. |
Traits
SizeOf | A trait for returning the size of a type in bytes. |
Attribute Macros
bench | testils Procedural macro for running DPDK based benches. |
test | testils Procedural macro for running DPDK based tests. |
Derive Macros
SizeOf | Derive macro for |